Access Entities Not Related to the Data Model

Overview

It is common to require access to Parameter and System entities that are not related to the data model, in order to extract information and use in XPath expressions.

In such cases, where the entities cannot be accessed directly through XPath navigation, the entity-list function is employed. The information returned by entity-list is handled as a collection of items. You need to iterate over the collection to access specific information (i.e., the item values).

Note:

entity-list should only be used to get and work with entities that are not related to the case and that cannot be accessed directly by navigating the data model with XPath.

Although this function uses XPath, it does not support the setXPath or newCollectionItem functions.

To set values to attributes of unrelated entities, use the CHelper.setAttrib function. As mentioned, setXPath does not work in these cases.

Syntax

Me.getXPath("entity-list('Entity','FilterExpression')", FilterParameters);

The Function Parameters

The Entity parameter: The name of the entity to access.
The FilterExpression parameter: Used at your discretion and it can be empty. This parameter filters the entity according to several conditions.
You can configure XPaths within your filters, e.g., "entity-list('Customer', 'city.country.code = @Code')".

Operators in Filters:

OPERATOR	NAME	EXAMPLE
=	Equals to	`'Client = @Client'`
<>	Other than	`'ClientName <> @ClientName'`
> , >=	Greater than / Greater than or equals to	`'Balance >= @Balance'`
<, <=	Less than / Less than or equals to	`'Balance <= @Balance'`
AND	And	`'Minimum <= @BorrowingCapacity> and Maximum >= @BorrowingCapacity'`
OR	Or	`'Minimum <= @BorrowingCapacity> and Maximum >= 1000'`
BETWEEN	Between	`'Balance BETWEEN @lowest AND @higher'`
IN ()	In	`"Balance in (@param1, @param2, @param3)"`
IS NULL	Equals null	`"CityName IS NULL"`
IS NOT NULL	Other than null	`"CityName IS NOT NULL"`

The FilterParameters parameter: Used to set the values of the parameters configured in the filter expression.
This parameter is a FilterParameters object, on which the parameters to be used in the filter are defined.
If the filter does not have filter parameters, do not use this parameter.

Example: Defining a `FilterParameters` Object

var parameters = new FilterParameters();
parameters.AddParameter("@Code", 1);
parameters.AddParameter("@Name", "John");

parameters.AddParameter("@Client", <Request.Client>);
parameters.AddParameter("@IsActive", false);

### Links for the Images and Icons:
1. **Icons**: [Link for icons here]
2. **Images**: [Link for images here]

var parameters = new FilterParameters();
parameters.AddParameter("@Code", 1);
parameters.AddParameter("@Name", "John");

parameters.AddParameter("@Client", <Request.Client>);
parameters.AddParameter("@IsActive", false);

How to Access the Entity's Information

The entity-list function is found in the Data navigation category.

Handling the Returned Entity

The returned entity is handled as a collection of items.
The entity collection must be stored in a variable to iterate over it.

To identify how many items the entity collection has, use the size() command.

Iterating Over the Collection

You can iterate through each item in the collection using a for loop. Below is an example:

// Define the filter parameters
var parameters = new FilterParameters();

parameters.AddParameter("@param1", value1);
parameters.AddParameter("@param2", value2);
.
.
.
parameters.AddParameter("@paramN", valueN);

// Get the identifier of the record
var Entity = Me.getXPath("entity-list('Entity','Filter')", parameters);

for (var Counter = 0; Counter < Entity.size(); Counter++) {
    // Get the attribute value of the record
    var Surrogate = Entity[Counter].getXPath("Id");
    var Value = Entity[Counter].getXPath("AttributeOfTheEntity");
}

//Define the filter parameters

 var parameters = new FilterParameters();

 parameters.AddParameter("@param1", value1);

 parameters.AddParameter("@param1", value1);

 .

 .

 .

 parameters.AddParameter("@paramN", valueN);

 //Get the identifier of the record

 var Entity = Me.getXPath("entity-list('Entity','Filter')", parameters);

 for(var Counter=0; Counter< Entity.size();Counter++)

 {

         //Get the attribute value of the record

         var Surrogate= Entity[Counter].getXPath("Id");

         var Value= Entity[Counter].getXPath("AttributeOfTheEntity");

 }

Example with no filter

An Onboarding Process requires the applicant to perform some medical tests prior to signing a contract.

These Medical Tests are saved in a Parameter entity, and are uploaded to a collection when the case requires them.

The following is the Data Model of the Onboarding Process.

The image below shows the list of all Medical tests that will be uploaded to the collection.

Go to the fourth step of the Bizagi Process Wizard. Add an expression to the On Enter action of the Task where the tests will be uploaded.
Write the code of the business rule to add the records of the Tests as elements in a collection.

Select the Get entity with entity-list function from the Data navigation category to access the Parameter entity.

//Evaluate if the collection has items

if(<count(Request.Applicant.ApplicantMedicalTests)> == 0)

{

 //Use the entity-list function to get all the Tests that will be added to the collection

 RequiredTest = Me.getXPath("entity-list('MedicalTest','')");

 //Iterate the variable in which the Tests are stored

 for(var Counter=0; Counter < RequiredTest.size(); Counter++)

 {

         //Add each Test to the collection

         NewTest = Me.newCollectionItem("Request.Applicant.ApplicantMedicalTests");

         NewTest.setXPath("MedicalTest",RequiredTest[Counter].getXPath("Id"));

 }

}

We will continue to use the Onboarding Process where the applicant must perform medical tests prior to signing a contract.

These Medical Tests are saved in a Parameter Entity and are uploaded to a collection when the case requires them. Only required tests should be added to the collection, and the associated Required attribute flagged.

Data Model of the Onboarding Process

The image below shows the list of all Medical Tests where only the records marked as required must be uploaded to the collection.

EntityManager3

Steps to Implement

Go to the fourth step of the Bizagi Process Wizard and create an On Enter action of the Task where the tests will be uploaded.
Write the code of the business rule to add the records of the required tests as elements to a collection.

Select the Get entity with entity-list function from the Data navigation category to access the Parameter entity.

Code Example

EntityManager5

// Evaluate if the collection has items
if (<count(Request.Applicant.ApplicantMedicalTests)> == 0) {
    // Define the filter parameters
    var parameters = new FilterParameters();
    parameters.AddParameter("@Required", true);

    // Use the entity-list function to get all the Tests to be added to the collection. Filter the records by the required status.
    RequiredTest = Me.getXPath("entity-list('MedicalTest','Required = @Required')", parameters);

    // Iterate the variable in which the Tests are stored
    for (var Counter = 0; Counter < RequiredTest.size(); Counter++) {
        // Add each Test to the collection
        NewTest = Me.newCollectionItem("Request.Applicant.ApplicantMedicalTests");
        NewTest.setXPath("MedicalTest", RequiredTest[Counter].getXPath("Id"));
        NewTest.setXPath("Delivered", RequiredTest[Counter].getXPath("Required"));
    }
}

if(<count(Request.Applicant.ApplicantMedicalTests)> == 0)

{

//Define the filter parameters

 var parameters = new FilterParameters();

 parameters.AddParameter("@Required", true);

//Use the entity-list function to get all the Tests to be added to the collection. Filter the records by the required status.

 RequiredTest = Me.getXPath("entity-list('MedicalTest','Required = @Required')",parameters);

//Iterate the variable in which the Tests are stored.

 for(var Counter=0; Counter < RequiredTest.size(); Counter++)

 {

//Add each Test to the collection.

         NewTest = Me.newCollectionItem("Request.Applicant.ApplicantMedicalTests");

         NewTest.setXPath("MedicalTest",RequiredTest[Counter].getXPath("Id"));

         NewTest.setXPath("Delivered",RequiredTest[Counter].getXPath("Required"));

 }

}

Example with Complex Filter

A bank requests certain documents for a Loans request, according to the Applicant's income and job role.

The Documents that apply for each case are stored in a Parameter entity called Documents per Applicant. For each case, there must be a rule that analyzes the Applicant's properties and adds the applicable documents to a collection.

The Documents per Applicant entity is not related to the data model. To obtain the records, you must use entity-list to iterate the entity and associate the documents with a collection of the data model.

Data Model of the Case

EntityManager10

The Parameter entities store the information to be evaluated in order to upload the applicable records as items of a collection:

EntityManager7
EntityManager8
EntityManager9

Steps to Implement

Go to the fourth step of the Bizagi Process Wizard. Add an expression to the On Enter action of the Task where the documents will be uploaded.
Write the code of the business rule to add the records of the Documents table as items to a collection.

Select the Get entity with entity-list function from the Data navigation category to access the Parameter entity.

Code Example

EntityManager6

// Create a filter to identify the role and the income source of the Applicant
var parameters = new FilterParameters();
parameters.AddParameter("@ApplicantRole", <Applicant.ApplicantRole.id>);
parameters.AddParameter("@IncomeSource", <Applicant.IncomeSource.id>);

// Use the entity-list function to get all the Documents to be added to the collection. Filter by the required status.
DocsXApplicant = Me.getXPath("entity-list('DocumentXApplicant','ApplicantRole = @ApplicantRole and IncomeSource = @IncomeSource')", parameters);

// Iterate the variable in which the Documents are stored
for (Count = 0; Count < DocsXApplicant.size(); Count++) {
    // Add each Document to the collection
    IdDocument = DocsXApplicant[Count].getXPath("Document");
    ApplicantDocument = Me.newCollectionItem("Applicant.Documents");
    ApplicantDocument.setXPath("Document", IdDocument);
    ApplicantDocument.setXPath("Required", DocsXApplicant[Count].getXPath("Required"));
}

var parameters = new FilterParameters();

parameters.AddParameter("@ApplicantRole", <Applicant.ApplicantRole.id>);

parameters.AddParameter("@IncomeSource", <Applicant.IncomeSource.id>);

//Use the entity-list function to get all the Documents to be added to the collection. Filter by the required status.

DocsXApplicant = Me.getXPath("entity-list('DocumentXApplicant','ApplicantRole = @ApplicantRole and IncomeSource = @IncomeSource')",parameters);

//Iterate the variable in which the Documents are stored.

for(Count =0; Count < DocsXApplicant.size(); Count++)

{

 //Add each Document to the collection

 IdDocument = DocsXApplicant[Count].getXPath("Document");

 ApplicantDocument = Me.newCollectionItem("Applicant.Documents");

 ApplicantDocument.setXPath("Document",IdDocument);

 ApplicantDocument.setXPath("Required",DocsXApplicant[Count].getXPath("Required"));

}

Example using dates in filter

A company dedicated to producing appliances uses Bizagi to manage warranties of their products. When a customer reports a problem with an appliance, a technician evaluates and determines which component is causing the appliance to fail. Once the defective component is identified, the company proceeds to request warranty to the supplier of this component. As suppliers change over time, records are kept to identify the period during which a supplier provided a specific component. This way, based on the production date of the appliance, the company can trace and easily identify to which supplier the warranty has to be requested.

Below is the data model of the case:

Data model of the case

The historical records of suppliers are stored in the SuppliersTrace entity. It contains the supplier, the component provided, and the period during which that supplier provided that component (supplier from (date), supplier to (date)).

To obtain the supplier that provided a specific component on a specific date, we will use the entity-list function, with SuppliersTrace as the entity and a filter that identifies the component and the date when it was supplied.

Steps:

Go to the fourth step of the Bizagi Process Wizard. Add an expression to the On Enter action of the Task where the supplier is identified.
Write the code of the business rule to obtain the supplier to which warranty for the component has to be requested.

Select the Get entity with entity-list function from the Data navigation category to access the Parameter entity.

Illustration:

Illustration of supplier identification

Example Code:

//Obtain the component and production date of the appliance and build the filter
var parameters = new FilterParameters();
parameters.AddParameter("@Component", <WarrantyRequest.Defectivecomponent>);
parameters.AddParameter("@ProductionDate", <WarrantyRequest.ProductionDate>);

//Use the entity-list function to get all the Suppliers that meet the Filter.
//We expect only one record because the effective period of a supplier is unique for a component.
var Suppliers = Me.getXPath("entity-list('SuppliersTraces','Component = @Component and SupplierFrom <= @ProductionDate and SupplierTo > @ProductionDate')", parameters);

//Obtain the record of the unique supplier of the list and assign it to the attribute of the process
<WarrantyRequest.SupplierToClaim> = Suppliers[0].getXPath("Supplier");

Sorting the entity's information

The entity's information is sorted by its entity ID by default, which means records appear in the order they were created.

To customize the order in which the information is retrieved, use the sort function.

Syntax of the sort function:

Me.getXPath(
  "sort(entity-list('Entity','FilterExpression'), 'AttributeOfTheEntity')",
  FilterParameters
);

Overview​

Syntax​

The Function Parameters​

Operators in Filters:​

Example: Defining a FilterParameters Object​

How to Access the Entity's Information​

Handling the Returned Entity​

Iterating Over the Collection​

Example with no filter​

Example with a Simple Attribute Filter​

Data Model of the Onboarding Process​

Steps to Implement​

Code Example​

Example with Complex Filter​

Data Model of the Case​

Steps to Implement​

Code Example​

Example using dates in filter​

Below is the data model of the case:​

Steps:​

Illustration:​

Example Code:​

Sorting the entity's information​

Syntax of the sort function:​

Overview

Syntax

The Function Parameters

Operators in Filters:

Example: Defining a `FilterParameters` Object

How to Access the Entity's Information

Handling the Returned Entity

Iterating Over the Collection

Example with no filter

Example with a Simple Attribute Filter

Data Model of the Onboarding Process

Steps to Implement

Code Example

Example with Complex Filter

Data Model of the Case

Steps to Implement

Code Example

Example using dates in filter

Below is the data model of the case:

Steps:

Illustration:

Example Code:

Sorting the entity's information

Syntax of the sort function: